/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			ETVpCommand.h
  \date			Sep 2011
  \author		TNick

  \brief		Contains the definition for ETVpCommand class


  Copyright (c) 2011, Nicu Tofan
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 * Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
 * Neither the name of the copyright holder nor the
   names of its contributors may be used to endorse or promote products
   derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL NICU TOFAN BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __ETVPCOMMAND_INC__
#define __ETVPCOMMAND_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<main.h>

class		ETSheetView;

class		QContextMenuEvent;
class		QDragEnterEvent;
class		QDragLeaveEvent;
class		QDragMoveEvent;
class		QDropEvent;
class		QKeyEvent;
class		QKeyEvent;
class		QMouseEvent;
class		QMouseEvent;
class		QMouseEvent;
class		QMouseEvent;
class		QPaintEvent;
class		QWheelEvent;

#include	<qglobal.h>

/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */

/// abstract class representing prerequisites for a command running in a ETSheetView
/**
*	Each view is able to maintain a command independent of other views.
*	Having multiple views looking at a single scene means that there may
*	be multiple commands running against same scene. To address possible
*	issues the view is required to only talk with the scene in "atomic"
*	operations (that can't overlap with operations from other views or
*	started from the code). As such, the (permanent) effect on the scene
*	is only commited when the command finishes and all input from the user
*	has been gathered. Commands may create temporary objects in the scene
*	to show an interactive interface, but are required to limit the use
*	of those as the effect is visible in other views, too.
*
*	The user first creates an instance of the command using the new() opperator.
*	Then, particular functions may be used to adjust the options relevan to
*	that command. Once the command is ready to be run, the pointer to
*	the command is passed to ETSheetView::startCommand(). In turn, this
*	will check the environment to make shure it's able to handle commands and
*	will make preparations for the command to run smoothly. It will also
*	call start() to inform the command that it's just about to begin. For
*	various reasons, any of these steps may fail or the command may
*	choose to perform the action it's intended to do in start(). If
*	ETSheetView::startCommand() returns true the command is running and the
*	ownership of the pointer is taken by the ETSheetView. If, on the other hand,
*	the function returns false, the ownership of the pointer remains with the
*	caller and it's its own responsability to release the memory using
*	\b delete() operator. The instance will be deleted during
*	ETSheetView::cancelCommand() call if the command is accepted.
*
*	Commands may be canceled by either calling ETSheetView::cancelCommand() or
*	ETSheetView::acceptCommand(). \b acceptCommand()
*	will inform the accept()
*	function, then will fall back to \b cancelCommand().
*	\b cancelCommand() simply
*	informs the command (class instance) about the event and deletes(!) the
*	class instance.
*
*	While a command is running mouse input and keyboard input is managed by it.
*
*/
class ETVpCommand 		{

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

private:



	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */

public:

	/// constructor;
	ETVpCommand		( void );

	/// destructor;
	virtual				~ETVpCommand		( void );


	/// the class is informed that the command is starting
	/**
 *	Commands are started by creating an instance of a class inherited from
 *	ETVpCommand and passing it to startCommand(). While current implementation
 *	will always call ETVpCommand::start(), this may change in the future. As a
 *	result the command (class) shall only initialise itself when it recieves
 *	the ETVpCommand::start(), not in constructor.
 *
 *	@return		true to continue loading or false to cancel
 */
	virtual bool		start		(
			ETSheetView *		trg_vp		/**< target viewport */
			) = 0;


	/// the class is informed that the command is being canceled
	/**
 *	The call to this function may or may not be preceded by a call to
 *	accepted(), depending on the user actions. It is usually called
 *	just before destroying the instance. However, the implementations
 *	shall free allocated resources here and not in destructor.
 */
	virtual void		cancel		(
			ETSheetView *		trg_vp		/**< target viewport */
			) = 0;


	/// the class is informed that the command is being accepted
	/**
 *	The command may or may not implement special functionality for this
 *	event. It is similar to an Ok button pushed in a dialog. The class
 *	is guaranteed to recieve a cancel() call just after the call to this
 *	function without any other calls to this class inbetween.
 */
	virtual void		accepted	(
			ETSheetView *		trg_vp		/**< target viewport */
			) { Q_UNUSED(trg_vp); }



public:

	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
	/** @name Events forwarded by the viewport    */
	//@{
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */

	virtual bool		context		(
			ETSheetView *	vp,
			QContextMenuEvent *	event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		dragEnter	(
			ETSheetView *	vp,
			QDragEnterEvent *	event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		dragLeave	(
			ETSheetView *	vp,
			QDragLeaveEvent *	event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		dragMove	(
			ETSheetView *	vp,
			QDragMoveEvent *	event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		drop		(
			ETSheetView *	vp,
			QDropEvent *	event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		keyPress	(
			ETSheetView *	vp,
			QKeyEvent *		event);

	virtual bool		keyRelease	(
			ETSheetView *	vp,
			QKeyEvent *		event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		mouseDoubleClick		(
			ETSheetView *	vp,
			QMouseEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		mouseMove	(
			ETSheetView *	vp,
			QMouseEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		mousePress	(
			ETSheetView *	vp,
			QMouseEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		mouseRelease(
			ETSheetView *	vp,
			QMouseEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		paint		(
			ETSheetView *	vp,
			QPaintEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	virtual bool		wheel		(
			ETSheetView *	vp,
			QWheelEvent * event)
	{ Q_UNUSED(vp); Q_UNUSED(event); return true; }

	//@}
	/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */


	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class ETVpCommand	*/

/*  CLASS    =============================================================== */
//
//
//
//
#endif // __ETVPCOMMAND_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
